Two slashes are used for single line comments. Anything on a line after a double slash // is ignored by the ray tracer. For example:
You can have scene file information on the line in front of the comment, as in:
The other type of comment is used for multiple lines. This It starts with /* and ends with */. Everything in-between is ignored. For example:
This can be useful if you want to temporarily remove elements from a scene file. /*...*/ comments can "comment out" lines containing other // comments, and thus can be used to temporarily or permanently comment out parts of a scene. /*..*/ comments can be nested, the following is legal:
Use comments liberally and generously. Well used, they really improve the readability of scene files.
Where POV-Ray needs an integer value it allows you to specify a float value and it truncates it to an integer. When POV-Ray needs a logical or boolean value it interprets any non-zero float as true and zero as false. Because float comparisons are subject to rounding errors, POV-Ray accepts values extremely close to zero as being false when doing boolean functions. Typically values whose absolute values are less than a preset value EPSILON are considered false for logical expressions. The value of EPSILON is system dependent but is generally about 1.0e-10. When comparing two floats A and B for equality, if abs(A-B)<EPSILON then (A=B) is considered true.
-2.0 -4 34 3.4e6 2e-5 .3 0.6
Where IDENTIFIER is the name of the identifier up to 40 characters long and EXPRESSION is any valid expression which evaluates to a float value. Here are some examples...
As the last example shows, you can re-declare a float identifier and may use previously declared values in that re-declaration. There are several built-in identifiers which POV-Ray declares for you. See "Built-in Identifiers" for details.
() expressions in parentheses first +A -A !A unary minus, unary plus and logical "not" A*B A/B multiplication and division A+B A-B addition and subtraction
Relational, logical, and conditional expressions may also be created. However there is a restriction that these types of expressions must be enclosed in parentheses first. This restriction, which is not imposed by most computer languages, is necessary because POV-Ray allows mixing of float and vector expressions. Without the parentheses there is an ambiguity problem. Parentheses are not required for the unary logical not operator "!" as shown above. The operators and their precedence are shown here.
Relational: Operands are arithmetic expressions. Result is always boolean with 1 for true, 0 for false. All relational operators have the same precedence.
| (A < B) | A is less than B |
| (A <= B) | A is less than or equal to B |
| (A = B) | A is equal to B (actually abs(A-B)<EPSILON) |
| (A != B) | A is not equal to B (actually abs(A-B)>=EPSILON) |
| (A >= B) | A is greater than or equal to B |
| (A > B) | A is greater than B |
Logical: Operands are converted to boolean values of 0 for false and 1 for true. Result is always boolean. All logical operators have the same precedence. Note these are not bitwise, they are logical.
| (A & B) | true only if both A and B are true, false otherwise |
| (A | B) | true if either A or B or both are true |
Conditional: Operand C is boolean. A and B are any expressions. Result is always whatever A or B are.
| (C ? A : B) | if C then A else B |
Assuming the various identifiers have been declared, the following are examples of valid expressions...
1+2+3 2*5 1/3 Row*3 Col*5 (Offset-5)/2 This/That+Other*Thing ((This<That) & (Other>=Thing)?Foo:Bar)
Expressions are evaluated left to right with innermost parentheses evaluated first, then unary +, - or !, then multiply or divide, then add or subtract, then relational, then logical, then conditional.
POV-Ray vectors may have from two to five components but the vast majority of vectors have three components. Unless specified otherwise, you should assume that the word "vector" means a three component vector. POV-Ray operates in a 3D x,y,z coordinate system and you will use three component vectors to specify x, y and z values. In some places POV-Ray needs only two coordinates. These are often specified by a 2D vector called a UV vector. Fractal objects use a 4D vector. Color expressions use 5D vectors but allow you to specify 3, 4 or 5 components and use default values for the unspecified components. Unless otherwise noted, all 2, 4 or 5 component vectors work just like 3D vectors but they have a different number of components.
The commas between components are necessary to keep the program from thinking that the 2nd term is a single float expression "3.2-5.4578" and that there is no 3rd term. If you see an error message such as Float expected but '>' found instead it probably means two floats were combined because a comma was missing.
Sometimes POV-Ray requires you to specify floats and vectors side-by-side. The rules for vector expressions allow for mixing of vectors with vectors or vectors with floats so commas are required separators whenever an ambiguity might arise. For example <1,2,3> -4 evaluates as a mixed float and vector expression where 4 is subtracted from each component resulting in <-3,-2,-1> however the comma here <1,2,3>,-4 means this is a vector followed by a float.
Each component may be a full float expression. For example <This+3,That/3,5*Other_Thing> is a valid vector.
Where IDENTIFIER is the name of the identifier up to 40 characters long and EXPRESSION is any valid expression which evaluates to a vector value. Here are some examples...
Note that you invoke a vector identifier by using its name without any angle brackets. As the last example shows, you can re-declare a vector identifier and may use previously declared values in that re-declaration. There are several built-in identifiers which POV-Ray declares for you. See "Built-in Identifiers" for details.
Conditional expressions such as (C?A:B) require that C is a float expression but A and B may be vector expressions. The result is that the entire conditional evaluates as a valid vector. For example if Foo and Bar are floats then ( Foo < Bar ? <1,2,3> : <5,6,7>) evaluates as the vector <1,2,3> if Foo is less than Bar and evaluates as <5,6,7> otherwise.
You may use the dot operator to extract a single component from a vector. Suppose the identifier "Spot" was previously defined as a vector. Then Spot.x is a float value that is the first component of this x,y,z vector. Similarly Spot.y and Spot.z reference the 2nd and 3rd components. If Spot was a two component uv_vector you could use Spot.u and Spot.v to extract the first and second component. For a 4D vector use .x .y .z and .t to extract each float component. The dot operator is also used in color expressions which are covered later.
Versions of POV-Ray prior to 3.0 only allowed such use of a float as a vector in various limited places such as scale and turbulence. However you may now use this trick anywhere. For example...
This automatic promotion is especially useful because it lets you mix floats and vectors in the same expression. For example in 3*<1,2,3> the 3 is promoted to <3,3,3> thus the expression is <3,3,3>*<1,2,3> which evaluates as <3,6,9>.
When promoting a float into a vector of 2, 3, 4 or 5 components, all components are set to the float value, however when promoting a vector of a lower number of components into a higher order vector, all remaining components are set to zero. For example if POV-Ray expects a 4D vector and you specify 9 the result is <9,9,9,9> but if you specify <7,6> the result is <7,6,0,0>.
The 4th component, called filter, specifies the amount of filtered transparency of a substance. Some real-world examples of filtered transparency are stained glass windows or tinted cellophane. The light passing through such objects is tinted by the appropriate color as the material selectively absorbs some frequencies of light while allowing others to pass through. The color of the object is subtracted from the light passing through so this is called subtractive transparency.
The 5th component, called transmit, specifies the amount of non-filtered light that is transmitted through a surface. Some real-world examples of non-filtered transparency are thin see-through cloth, fine mesh netting and dust on a surface. In these examples, all frequencies of light are allowed to pass through tiny holes in the surface. Although the amount of light passing through is diminished, the color of the light passing through is unchanged. The color of the object is added to the light passing through so this is called additive transparency.
Note: Early versions of POV-Ray used the keyword alpha to specify filtered transparency however that word is often used to descrbe non-filtered transparency. For this reason, alpha is no longer used.
Each of the five components of a color are float values which are normally in the range between 0.0 and 1.0 however any values, even negatives may be used.
Colors may be specified using vectors, keywords with floats, or identifiers. You may also create very complex color expressions from combinations any of these using various familiar operators. The syntax for specifying a color has evolved since POV-Ray was first released. We have maintained the original keyword-based syntax and added a short-cut vector notation. Either the old or new syntax is acceptable however the vector syntax is easier to use when creating color expressions.
where VECTOR3, VECTOR4 or VECTOR5 are any valid vector expressions of 3, 4 or 5 components. For example
This specifies a color whose red component is 1.0 or 100% of full intensity; the green component is 0.5 or 50% of full intensity and the blue component is 0.2 or 20% of full intensity. Although the filter and transmit components are not explicitly specified, they exist and are set to their default values of 0 or no transparency.
The rgbf keyword requires a four component vector. The 4th component is the filter component and the transmit component defaults to zero. Similarly the rgbt keyword requires four components where the 4th value is moved to the 5th component which is transmit and then the filter component is set to zero.
The rgbft keyword allows you to specify all five components. Internally in expressions all five are always used.